# Audio: Mobile Audio Player

The audio module provides many interfaces for applications to access the audio player. These interfaces can open an audio player to play audio, and can even be used to implement a customized music player.

Developers can determine whether these interfaces work in the EdgerOS mobile App environment through the following code:

edger.env().then(data => {
  if (data.env === 'edgerapp') {
    // We work in EdgerOS mobile App environment.
  }
}).catch(error => {
  console.error(error)
})

# Functions

# edger.audio.play(options)

Initialize and open the audio player.

• options {AudioPlayerOptions} The initialization parameters of the audio player. It can contain the following members:
  • headless {Boolean} Whether to use headless playback, when false, the player's default style will be used. Default: false.
  • index {Number} The index of audio files, you can specify which file to start playing from. Default: 0. Optional.
  • position {Number} The current playback progress of audio, you can specify where to start playing. Default: 0. Unit: second(s). Optional.
  • autoPlay {Boolean} Whether to play automatically. Default: false. Optional.
  • speed {AudioSpeed} The playback speed of audio, you can specify the initial value of the player's playback speed. Optional values: 0.5 | 1 | 1.5 | 2. Default: 1. Optional.
  • mode {AudioPlayMode} The mode of audio player. Optional values: repeat_mode_one | repeat_mode_all | repeat_mode_random, the meaning of these values is single loop, list cycle, random playback. Default: repeat_mode_all. Optional.
  • files {Array<AudioFile>} Audio files. The files attribute is an audio file array, each audio file item contains the following members:
    • name {String} The name of audio file.
    • url {String} The url of audio file.
    • id {String} The ID of audio file. Optional.
    • cover {String} The cover image url of audio file. Optional.
    • author {String} The author of audio file. Optional.
    • size {Number} The size of audio file. Unit: Byte(B). Optional.
    • headers {Object} Custom request header information. Optional.
  • toolbar {Array<AudioToolbar>} The toolbar items of the player, it can contain the following members:
    • icon {String} The icon for the toolbar item.
    • code {String} The type code for the toolbar item.
    • label {String} The title for the toolbar item.
    • disabled {Boolean} Indicates whether the toolbar item is disabled. Optional.
    • position {String} The display position for the toolbar item. Optional values: top | bottom. Default: bottom. Optional.
    • labelColor {String} The font color for the toolbar item. Optional.
    • labelBgColor {String} The background color for the toolbar item. Optional.
• Returns: {Promise}.

# Example

const params = {
  autoPlay: true,
  position: 0,
  headless: true,
  files: [
    {
      name: '晴天',
      author: '周杰伦',
      cover: 'https://p1.music.126.net/RGsJyDuaOVNx0Mt0AvByQQ==/109951166994369315.jpg?param=400y400',
      url: 'https://ax5mtor-ap3lafm.qddo1m-2oo83d.edgeros.vip/1.mp3',
      size: 3505048
    },
    {
      cover: 'https://p1.music.126.net/8g2Pn9Xw1m7cFhxOlc3BMg==/109951167875709379.jpg?param=400y400',
      name: '蓝莲花',
      author: '许巍',
      url: 'https://ax5mtor-ap3lafm.qddo1m-2oo83d.edgeros.vip/2.mp3',
      size: 3808487
    }
  ],
  toolbar: [
    {
      icon: 'computer',
      code: 'computer',
      label: '投屏',
      disabled: false,
      position: 'bottom',
      labelColor: '#000'
    },
    { icon: 'delete1', code: 'delete1', label: '删除', disabled: true },
    { icon: 'export', code: 'export', label: '导出', disabled: false },
    { icon: 'details', code: 'details', label: '详情' }
  ]
}

edger.audio.play(params)

# async / await

async function audioPlay() {
  try {
    await edger.audio.play(params)
  } catch (error) {
    console.error(error)
  }
}

# edger.audio.setToolbar(params)

Set the toolbar for the audio player.

• params {Object} The parameters of the audio toolbar, it can contain the following members:
• toolbar {Array<AudioToolbar>} The toolbar items of the player, it can contain the following members:
  • icon {String} The icon for the toolbar item.
  • code {String} The type code for the toolbar item.
  • label {String} The title for the toolbar item.
  • disabled {Boolean} Indicates whether the toolbar item is disabled. Optional.
  • position {String} The display position for the toolbar item. Optional values: top | bottom. Default: bottom. Optional.
  • labelColor {String} The font color for the toolbar item. Optional.
  • labelBgColor {String} The background color for the toolbar item. Optional.
• Returns: {Promise}.

Get an object of result, the object includes:

• code {String} The type code for the toolbar item.
• id {String} Audio file ID.

# Example

const updateToolbar = [
  {
    icon: 'computer',
    code: 'computer',
    label: '投屏',
    disabled: false,
    position: 'bottom',
    labelColor: '#0077fa'
  },
  { icon: 'delete1', code: 'delete1', label: '删除', disabled: false },
  { icon: 'export', code: 'export', label: '导出', disabled: true }
]

edger.audio.play(params).then(() => {
  edger.audio.setToolbar({ toolbar: updateToolbar }).then(() => {})
})

# async / await

async function audioSetToolbar() {
  try {
    await edger.audio.play(params)
    await edger.audio.setToolbar({ toolbar: updateToolbar })
  } catch (error) {
    console.error(error)
  }
}

# edger.audio.delete(params)

Delete audio files from the playlist based on the index.

• params {Object} The parameters of the audio delete, it can contain the following member:
  • index {Number} The index of audio files.
• Returns: {Promise}.

# Example

edger.audio.delete({ index: 1 }).then(() => {})

# async / await

async function audioDelete() {
  try {
    await edger.audio.delete({ index: 1 })
  } catch (error) {
    console.error(error)
  }
}

# edger.audio.destroy()

Destroy the audio player.

• Returns: {Promise} .

# Example

edger.audio.destroy().then(() => {})

# async / await

async function audioDestroy() {
  try {
    await edger.audio.destroy()
  } catch (error) {
    console.error(error);
  }
}

# Events

The unified event listener provided by Web-SDK:

const listener = (payload) => {
  // Event handling...
}

// add listener
edger.audio.addEventListener('some-event', listener)

// or 
// onAction() is an alias of addEventListener().
edger.audio.onAction('some-event', listener)

// remove listener
edger.audio.removeEventListener('some-event', listener)

// remove all listeners
edger.audio.removeAllListeners()

# change

Triggered when the playback item changes, for example, the previous song and the next song.

• Returns: {Object} An object.

Get an object of result, the object includes:

• id {String} Audio file ID. Optional.
• previous: {Number} Index of the previous audio file.
• current: {Number} Index of the current audio file.
• total: {Number} The total number of audio files in the list.

# Example

edger.audio.addEventListener('change', (payload) => {
  console.log("change res:", payload)
})

# status

Triggered when the player's state changes.

• Returns: {Object} An object.

Get an object of result, the object includes:

• status: {String} The audio player's state. Optional values: pause | playing | destroy.

# Example

edger.audio.addEventListener('status', (payload) => {
  console.log("status res:", payload)
})

# action

Triggered after clicking an item in the toolbar of the audio player.

• Returns: {Object} An object.

Get an object of result, the object includes:

• id {String} Audio file ID. Optional.
• code {String} Action type code.
• index: {Number}: Index of the audio files.

# Example

edger.audio.addEventListener('action', (payload) => {
  console.log("action code:", payload.code)
})